docs: Refactor documentation to use tested example applications#890
Open
hey-granth wants to merge 3 commits into
Open
docs: Refactor documentation to use tested example applications#890hey-granth wants to merge 3 commits into
hey-granth wants to merge 3 commits into
Conversation
- Replace static code-block directives with literalinclude in quickstart, admin, managers, formsets, and advanced rst files. - Implement executable example apps in src/polymorphic/tests/examples/ to provide verified source material for documentation. - Update test settings to include new example apps in INSTALLED_APPS for automated validation. - Add unit tests for each documentation example to ensure ongoing code accuracy. - Correct admin inline relationship field names to resolve E202 system check errors in the example suite.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refactors django-polymorphic documentation so that major code examples are pulled directly from executable “example apps” under src/polymorphic/tests/examples/, with the intent that the test suite prevents documentation drift (Issue #811).
Changes:
- Added multiple new example apps (models + tests + migrations) that mirror documented use-cases (quickstart, admin, managers, formsets, advanced).
- Updated docs (
quickstart.rst,admin.rst,managers.rst,formsets.rst,advanced.rst) to use Sphinxliteralincluderather than static code blocks. - Integrated the new example apps into the test settings via
INSTALLED_APPSso they’re exercised in CI.
Reviewed changes
Copilot reviewed 45 out of 55 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/polymorphic/tests/settings.py | Adds new example apps to the test environment so their code/docs can be validated by the test suite. |
| src/polymorphic/tests/examples/views/test.py | Formatting-only adjustments to existing UI test code. |
| src/polymorphic/tests/examples/type_hints/one2one/test.py | Formatting-only adjustments to type-hints tests. |
| src/polymorphic/tests/examples/type_hints/managers/test.py | Formatting-only adjustments to type-hints tests. |
| src/polymorphic/tests/examples/type_hints/m2m/test.py | Formatting-only adjustments to type-hints tests. |
| src/polymorphic/tests/examples/type_hints/m2m/models.py | Formatting-only adjustments to type-hints models. |
| src/polymorphic/tests/examples/type_hints/fk/test.py | Formatting-only adjustments to type-hints tests. |
| src/polymorphic/tests/examples/quickstart/tests.py | New executable quickstart example (as a Django test). |
| src/polymorphic/tests/examples/quickstart/models.py | New quickstart example models used by docs + tests. |
| src/polymorphic/tests/examples/quickstart/migrations/0002_alter_project_polymorphic_ctype.py | Migration for quickstart example app. |
| src/polymorphic/tests/examples/quickstart/migrations/0001_initial.py | Initial schema for quickstart example app. |
| src/polymorphic/tests/examples/quickstart/migrations/init.py | Marks quickstart migrations package. |
| src/polymorphic/tests/examples/quickstart/apps.py | AppConfig for quickstart example app (custom label). |
| src/polymorphic/tests/examples/quickstart/init.py | Quickstart example package init. |
| src/polymorphic/tests/examples/managers/tests.py | New manager-focused example tests. |
| src/polymorphic/tests/examples/managers/models.py | New manager-focused example models/managers/querysets. |
| src/polymorphic/tests/examples/managers/migrations/0002_alter_mymodel_managers_alter_myothermodel_managers_and_more.py | Migration adjustments for managers example app. |
| src/polymorphic/tests/examples/managers/migrations/0001_initial.py | Initial schema for managers example app. |
| src/polymorphic/tests/examples/managers/migrations/init.py | Marks managers migrations package. |
| src/polymorphic/tests/examples/managers/apps.py | AppConfig for managers example app (custom label). |
| src/polymorphic/tests/examples/managers/init.py | Managers example package init. |
| src/polymorphic/tests/examples/integrations/reversion/test.py | Formatting-only adjustments to integration tests. |
| src/polymorphic/tests/examples/integrations/guardian/test.py | Formatting-only adjustments to integration tests. |
| src/polymorphic/tests/examples/integrations/extra_views/test.py | Formatting-only adjustments to integration tests. |
| src/polymorphic/tests/examples/integrations/drf/test.py | Formatting-only adjustments to integration tests. |
| src/polymorphic/tests/examples/integrations/drf/models/filters.py | Formatting-only adjustments to integration example models. |
| src/polymorphic/tests/examples/integrations/drf/filter_views.py | Formatting-only adjustments to filtering example code. |
| src/polymorphic/tests/examples/integrations/drf/filter_serializers.py | Formatting-only adjustments to serializer example code. |
| src/polymorphic/tests/examples/formsets/tests.py | New formsets example test demonstrating factory + save flow. |
| src/polymorphic/tests/examples/formsets/models.py | New formsets example models. |
| src/polymorphic/tests/examples/formsets/migrations/0002_alter_modela_polymorphic_ctype.py | Migration for formsets example app. |
| src/polymorphic/tests/examples/formsets/migrations/0001_initial.py | Initial schema for formsets example app. |
| src/polymorphic/tests/examples/formsets/migrations/init.py | Marks formsets migrations package. |
| src/polymorphic/tests/examples/formsets/apps.py | AppConfig for formsets example app (custom label). |
| src/polymorphic/tests/examples/formsets/init.py | Formsets example package init. |
| src/polymorphic/tests/examples/advanced/tests.py | New advanced examples expressed as executable tests. |
| src/polymorphic/tests/examples/advanced/models.py | New advanced example models. |
| src/polymorphic/tests/examples/advanced/migrations/0002_alter_modela_polymorphic_ctype.py | Migration for advanced example app. |
| src/polymorphic/tests/examples/advanced/migrations/0001_initial.py | Initial schema for advanced example app. |
| src/polymorphic/tests/examples/advanced/migrations/init.py | Marks advanced migrations package. |
| src/polymorphic/tests/examples/advanced/apps.py | AppConfig for advanced example app (custom label). |
| src/polymorphic/tests/examples/advanced/init.py | Advanced example package init. |
| src/polymorphic/tests/examples/admin/tests.py | New admin example tests covering parent/child admin + inlines. |
| src/polymorphic/tests/examples/admin/models.py | New admin example models used by docs/tests. |
| src/polymorphic/tests/examples/admin/migrations/0002_alter_modela_polymorphic_ctype_and_more.py | Migration for admin example app. |
| src/polymorphic/tests/examples/admin/migrations/0001_initial.py | Initial schema for admin example app. |
| src/polymorphic/tests/examples/admin/migrations/init.py | Marks admin migrations package. |
| src/polymorphic/tests/examples/admin/apps.py | AppConfig for admin example app (custom label). |
| src/polymorphic/tests/examples/admin/admin.py | New admin registrations and inline configurations for docs/tests. |
| src/polymorphic/tests/examples/admin/init.py | Admin example package init. |
| docs/quickstart.rst | Switches quickstart docs to literalinclude-based snippets. |
| docs/managers.rst | Switches manager docs to literalinclude-based snippets tied to tests. |
| docs/formsets.rst | Switches formset docs to literalinclude-based snippets tied to tests. |
| docs/advanced.rst | Replaces large prose + code sections with literalincludes from example tests/models. |
| docs/admin.rst | Switches admin docs to literalinclude-based snippets tied to example app/tests. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+107
to
+112
| INSTALLED_APPS = [ | ||
| "polymorphic.tests.examples.quickstart", | ||
| "polymorphic.tests.examples.admin", | ||
| "polymorphic.tests.examples.managers", | ||
| "polymorphic.tests.examples.formsets", | ||
| "polymorphic.tests.examples.advanced", |
Comment on lines
10
to
15
| .. literalinclude:: ../src/polymorphic/tests/settings.py | ||
| :caption: src/polymorphic/tests/settings.py (INSTALLED_APPS excerpt) | ||
| :language: python | ||
| :lines: 100-121 | ||
| :linenos: | ||
|
|
Comment on lines
3
to
+8
| Advanced Features | ||
| ================= | ||
|
|
||
| In the examples below, these models are being used: | ||
|
|
||
| .. code-block:: python | ||
| .. literalinclude:: ../src/polymorphic/tests/examples/advanced/models.py |
…ion context - Update INSTALLED_APPS in test settings to use explicit AppConfig class paths for all example apps to ensure migration labels match. - Replace internal test settings literalinclude in quickstart.rst with a minimal production-ready code block. - Restore explanatory prose, instructional sections, and technical caveats in advanced.rst while maintaining literalinclude for code snippets. - Validate infrastructure via successful system checks and migration-sensitive test execution.
Author
|
hii @bckohan, any updates on this? do i need to make any changes for it to be better suited to the project? |
Member
It looks like there are quite a few semantic documentation changes included with this PR. See all the AI code review comments. For example: this PR: current: #811 is about testing any remaining sample code included in the docs without changing any semantic content of the docs. Sample code should also be as close to the current docs as possible with minimal inclusion of test cruft |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request refactors the
django-polymorphicdocumentation to ensure major code examples are executable and verified by the test suite. Static code blocks are replaced with the Sphinx.. literalinclude::directive to eliminate documentation rot and guarantee functional logic for users.Solves #811
Key Changes
quickstart.rst,admin.rst,managers.rst,formsets.rst, andadvanced.rstto pull code snippets directly from source files.src/polymorphic/tests/examples/mirroring documented use cases.INSTALLED_APPSwithinsrc/polymorphic/tests/settings.pyfor automated validation.tests.pyfor each example app to verify polymorphic queries, admin configurations, and formset logic.admin.E202system check errors.Verification
sphinx-build -b html docs/ docs/_build/htmlas the environment lacked a directmakerule for thehtmltarget. Output accurately reflects source code logic.python manage.py checkwith no identified issues.